Update `channel_reestablish` for splicing #3886

jkczyz · 2025-06-24T00:12:11Z

The splicing spec extends the channel_reestablish message with two more TLVs indicating which funding txid the sender has sent/received either explicitly via splice_locked or implicitly via channel_ready. This allows peers to detect if a splice_locked was lost during disconnection and must be retransmitted.

To this end, the spec updates the channel_reestablish logic to support splicing.

ldk-reviews-bot · 2025-06-24T00:12:14Z

🎉 This PR is now ready for review!
Please choose at least one reviewer by assigning them on the right bar.
If no reviewers are assigned within 10 minutes, I'll automatically assign one.
Once the first reviewer has submitted a review, a second will be assigned if required.

ldk-reviews-bot · 2025-06-26T00:13:17Z

🔔 1st Reminder

Hey @wpaulino! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

jkczyz · 2025-06-27T17:12:50Z

@wpaulino Ready for review now.

codecov · 2025-06-27T17:13:47Z

Codecov Report

Attention: Patch coverage is 59.22747% with 95 lines in your changes missing coverage. Please review.

Project coverage is 89.42%. Comparing base (0fe51c5) to head (f000b76).
Report is 20 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/ln/channel.rs	43.82%	85 Missing and 6 partials ⚠️
lightning/src/ln/channelmanager.rs	83.33%	1 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3886      +/-   ##
==========================================
- Coverage   89.66%   89.42%   -0.24%     
==========================================
  Files         164      165       +1     
  Lines      134661   126319    -8342     
  Branches   134661   126319    -8342     
==========================================
- Hits       120743   112967    -7776     
+ Misses      11237    10971     -266     
+ Partials     2681     2381     -300

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ldk-reviews-bot · 2025-06-28T00:14:12Z

🔔 2nd Reminder

Hey @wpaulino! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-06-30T00:15:02Z

🔔 3rd Reminder

Hey @wpaulino! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-02T00:15:46Z

🔔 4th Reminder

Hey @wpaulino! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-05T00:01:02Z

🔔 5th Reminder

Hey @wpaulino! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-07-07T00:01:48Z

🔔 6th Reminder

Hey @wpaulino! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

While splicing is not yet fully supported, checking if the feature has been negotiated is needed for changes to the channel_reestablish logic.

jkczyz · 2025-07-07T21:03:02Z

Rebased.

wpaulino

We may need to double check our incoming channel_ready handling to make sure we can handle receiving one long after channel_ready was already exchanged due to the new logic surrounding your_last_funding_locked_txid.

lightning-types/src/features.rs

wpaulino · 2025-07-07T21:38:51Z

lightning/src/ln/channel.rs

@@ -1665,12 +1665,12 @@ where
 	/// send our peer to begin the channel reconnection process.
 	#[rustfmt::skip]
 	pub fn peer_connected_get_handshake<L: Deref>(
-		&mut self, chain_hash: ChainHash, logger: &L,
+		&mut self, chain_hash: ChainHash, features: &InitFeatures, logger: &L,


remote_features*

Using their_features for consistency with other methods.

wpaulino · 2025-07-07T21:40:14Z

lightning/src/ln/channel.rs

+	#[cfg(not(splicing))]
+	fn maybe_get_your_last_funding_locked_txid(&self, _features: &InitFeatures) -> Option<Txid> {
+		None
+	}


Looks like we could avoid the not(splicing) variants by just doing this inline above

It would keep the blame history cleaner this way as doing that would require introducing an indentation. That is, because of PendingSplice, we still need something like:

#[cfg(not(splicing))] { self.pending_splice .as_ref() .and_then(|pending_splice| pending_splice.received_funding_txid) // ... } #[cfg(not(splicing))] { None }

wpaulino · 2025-07-07T21:40:34Z

lightning/src/ln/channel.rs

@@ -9381,6 +9381,13 @@ where
 		self.context.latest_inbound_scid_alias.or(self.funding.get_short_channel_id())
 	}

+	/// Returns true if their channel_ready has been received
+	#[cfg(splicing)]


This is called by maybe_get_your_last_funding_locked_txid which needs PendingSplice. Without it we get a build warning.

wpaulino · 2025-07-07T21:42:12Z

lightning/src/ln/channel.rs

@@ -10128,10 +10135,52 @@ where
 		}
 	}

+	#[cfg(splicing)]
+	fn maybe_get_your_last_funding_locked_txid(&self, features: &InitFeatures) -> Option<Txid> {
+		if !features.supports_splicing() {


Since the TLVs are optional, I don't think we really need to check this and can always set them

Hmm.. if the implementation supports splicing but didn't set the feature bit, won't they understand the TLV?

wpaulino · 2025-07-07T21:54:56Z

lightning/src/ln/channel.rs

+			msg.your_last_funding_locked_txid
+				.is_none()
+				.then(|| ())
+				.and_then(|_| self.get_channel_ready(logger))


Hmm, I would've expected this to check that we can actually send channel_ready, but we don't seem to check it above either...

Does the early return above handle that?

rust-lightning/lightning/src/ln/channel.rs

Lines 8349 to 8365 in 725be21

if matches!(self.context.channel_state, ChannelState::AwaitingChannelReady(_)) {

// If we're waiting on a monitor update, we shouldn't re-send any channel_ready's.

if !self.context.channel_state.is_our_channel_ready() ||

self.context.channel_state.is_monitor_update_in_progress() {

if msg.next_remote_commitment_number != 0 {

return Err(ChannelError::close("Peer claimed they saw a revoke_and_ack but we haven't sent channel_ready yet".to_owned()));

}

// Short circuit the whole handler as there is nothing we can resend them

return Ok(ReestablishResponses {

channel_ready: None,

raa: None, commitment_update: None,

order: RAACommitmentOrder::CommitmentFirst,

shutdown_msg, announcement_sigs,

tx_signatures: None,

tx_abort: None,

});

}

wpaulino · 2025-07-07T22:17:40Z

lightning/src/ln/channel.rs

+				&& !session.has_received_commitment_signed()
+			{
+				// FIXME
+				return unimplemented!();


wpaulino · 2025-07-07T22:44:34Z

lightning/src/ln/channel.rs

+			self.pending_funding
+				.iter()
+				.find(|funding| funding.get_funding_txid() == Some(funding_txid))
+				.and_then(|_| {
+					self.pending_splice.as_ref().and_then(|pending_splice| {


Any reason to iterate over pending_funding when we know it should exist if a splice_locked was sent for it?

They could have sent any arbitrary my_current_funding_locked_txid, so we need to check if we are aware of it. Maybe that is redundant with checks when the implicit splice_locked is processed? At very least this is explicitly following the language in the spec. Also, my_current_funding_locked_txid could have been their channel_ready, so we wouldn't want to infer a splice_locked from that.

wpaulino · 2025-07-07T22:46:05Z

lightning/src/ln/channel.rs

+				.find(|funding| funding.get_funding_txid() == Some(funding_txid))
+				.and_then(|_| {
+					self.pending_splice.as_ref().and_then(|pending_splice| {
+						(Some(funding_txid) != pending_splice.received_funding_txid)


Shouldn't this be checking sent_funding_txid instead? Isn't this handling the case where we sent our splice_locked, didn't get to process theirs even though they sent it, and are now reconnecting?

Whether we sent ours isn't important here. This is checking if we've seen the splice_locked that they claimed to have last sent. Either pending_splice.received_funding_txid is some other txid that they had previously sent or None if we don't think they have sent one yet.

wpaulino · 2025-07-07T22:47:29Z

lightning/src/ln/channelmanager.rs

+		if let Some(splice_locked) = implicit_splice_locked {
+			self.internal_splice_locked(counterparty_node_id, &splice_locked)?;
+		}
+
 		Ok(NotifyOption::SkipPersistHandleEvents)


We'll need to persist if we promoted the scope above

Looks like we always persist when internal_splice_locked returns Ok, so doing that here, too.

ldk-reviews-bot · 2025-07-07T22:48:56Z

👋 The first review has been submitted!

Do you think this PR is ready for a second reviewer? If so, click here to assign a second reviewer.

The splicing spec extends the channel_reestablish message with two more TLVs indicating which funding txid the sender has sent/received either explicitly via splice_locked or implicitly via channel_ready. This allows peers to detect if a splice_locked was lost during disconnection and must be retransmitted. This commit updates channel_reestablish with the TLVs. Subsequent commits will implement the spec requirements.

The previous commit extended the channel_reestablish message with your_last_funding_locked_txid and my_current_funding_locked_txid for use as described there. This commit sets those fields to the funding txid most recently sent/received accordingly.

When splicing is negotiated, channel_ready must be retransmitted when your_last_funding_locked is not set. Further, the current logic for retransmitting channel_ready is only applicable when splicing is not negotiated.

The splicing spec updates the logic pertaining to next_funding_txid when handling a channel_reestablish message. Specifically: A receiving node: - if `next_funding_txid` is set: - if `next_funding_txid` matches the latest interactive funding transaction or the current channel funding transaction: - if `next_commitment_number` is equal to the commitment number of the `commitment_signed` message it sent for this funding transaction: - MUST retransmit its `commitment_signed` for that funding transaction. - if it has already received `commitment_signed` and it should sign first, as specified in the [`tx_signatures` requirements](#the-tx_signatures-message): - MUST send its `tx_signatures` for that funding transaction. - if it has already received `tx_signatures` for that funding transaction: - MUST send its `tx_signatures` for that funding transaction. - if it also sets `next_funding_txid` in its own `channel_reestablish`, but the values don't match: - MUST send an `error` and fail the channel. - otherwise: - MUST send `tx_abort` to let the sending node know that they can forget this funding transaction. This commit updates FundedChannel::channel_reestablish accordingly. Co-authored-by: Wilmer Paulino <[email protected]> Co-authored-by: Jeffrey Czyz <[email protected]>

The splicing spec updates the logic pertaining to next_commitment_number when sending a channel_reestablish message. Specifically: The sending node: - if it has sent `commitment_signed` for an interactive transaction construction but it has not received `tx_signatures`: - MUST set `next_funding_txid` to the txid of that interactive transaction. - if it has not received `commitment_signed` for that interactive transaction: - MUST set `next_commitment_number` to the commitment number of the `commitment_signed` it sent.

The channel_reestablish protocol supports retransmitting splice_locked messages as needed. Add support for doing such when handling channel_reestablish messages.

The splicing spec updates channel_establishment logic to retransmit channel_ready or splice_locked for announced channels. Specifically: - if `my_current_funding_locked` is included: - if `announce_channel` is set for this channel: - if it has not received `announcement_signatures` for that transaction: - MUST retransmit `channel_ready` or `splice_locked` after exchanging `channel_reestablish`.

When a splice transaction is promoted (i.e., when splice_locked has been exchanged), announcement_signatures must be sent. However, if we try to send a channel_announcement before they are received, then the signatures will be incorrect. To avoid this, clear the counterparty's announcement_signatures upon promoting a FundingScope.

The channel_reestablish protocol supports retransmitting channel_ready messages as needed. Add support for doing such when handling channel_reestablish messages.

When handling a counterparties channel_reestablish, the spec dictates that a splice_locked may be implied by my_current_funding_locked. Compare that against any pending splices and handle an implicit splice_locked message when applicable.

jkczyz

We may need to double check our incoming channel_ready handling to make sure we can handle receiving one long after channel_ready was already exchanged due to the new logic surrounding your_last_funding_locked_txid.

ACK. Also need to address https://github.com/lightningdevkit/rust-lightning/pull/3736/files#r2133028859.

jkczyz · 2025-07-08T23:04:49Z

lightning/src/ln/channel.rs

@@ -1665,12 +1665,12 @@ where
 	/// send our peer to begin the channel reconnection process.
 	#[rustfmt::skip]
 	pub fn peer_connected_get_handshake<L: Deref>(
-		&mut self, chain_hash: ChainHash, logger: &L,
+		&mut self, chain_hash: ChainHash, features: &InitFeatures, logger: &L,


Using their_features for consistency with other methods.

jkczyz · 2025-07-08T23:08:12Z

lightning/src/ln/channel.rs

@@ -9381,6 +9381,13 @@ where
 		self.context.latest_inbound_scid_alias.or(self.funding.get_short_channel_id())
 	}

+	/// Returns true if their channel_ready has been received
+	#[cfg(splicing)]


This is called by maybe_get_your_last_funding_locked_txid which needs PendingSplice. Without it we get a build warning.

jkczyz · 2025-07-08T23:10:35Z

lightning/src/ln/channel.rs

@@ -10128,10 +10135,52 @@ where
 		}
 	}

+	#[cfg(splicing)]
+	fn maybe_get_your_last_funding_locked_txid(&self, features: &InitFeatures) -> Option<Txid> {
+		if !features.supports_splicing() {


Hmm.. if the implementation supports splicing but didn't set the feature bit, won't they understand the TLV?

jkczyz · 2025-07-08T23:12:03Z

lightning/src/ln/channel.rs

+	#[cfg(not(splicing))]
+	fn maybe_get_your_last_funding_locked_txid(&self, _features: &InitFeatures) -> Option<Txid> {
+		None
+	}


It would keep the blame history cleaner this way as doing that would require introducing an indentation. That is, because of PendingSplice, we still need something like:

#[cfg(not(splicing))] { self.pending_splice .as_ref() .and_then(|pending_splice| pending_splice.received_funding_txid) // ... } #[cfg(not(splicing))] { None }

jkczyz · 2025-07-08T23:38:19Z

lightning/src/ln/channel.rs

+			msg.your_last_funding_locked_txid
+				.is_none()
+				.then(|| ())
+				.and_then(|_| self.get_channel_ready(logger))


Does the early return above handle that?

rust-lightning/lightning/src/ln/channel.rs

Lines 8349 to 8365 in 725be21

if matches!(self.context.channel_state, ChannelState::AwaitingChannelReady(_)) {

// If we're waiting on a monitor update, we shouldn't re-send any channel_ready's.

if !self.context.channel_state.is_our_channel_ready() ||

self.context.channel_state.is_monitor_update_in_progress() {

if msg.next_remote_commitment_number != 0 {

return Err(ChannelError::close("Peer claimed they saw a revoke_and_ack but we haven't sent channel_ready yet".to_owned()));

}

// Short circuit the whole handler as there is nothing we can resend them

return Ok(ReestablishResponses {

channel_ready: None,

raa: None, commitment_update: None,

order: RAACommitmentOrder::CommitmentFirst,

shutdown_msg, announcement_sigs,

tx_signatures: None,

tx_abort: None,

});

}

jkczyz · 2025-07-08T23:43:07Z

lightning/src/ln/channel.rs

@@ -8277,7 +8277,8 @@ where
 	#[rustfmt::skip]
 	pub fn channel_reestablish<L: Deref, NS: Deref>(
 		&mut self, msg: &msgs::ChannelReestablish, logger: &L, node_signer: &NS,
-		chain_hash: ChainHash, user_config: &UserConfig, best_block: &BestBlock
+		chain_hash: ChainHash, features: &InitFeatures, user_config: &UserConfig,


jkczyz · 2025-07-08T23:50:55Z

lightning/src/ln/channel.rs

+			self.pending_funding
+				.iter()
+				.find(|funding| funding.get_funding_txid() == Some(funding_txid))
+				.and_then(|_| {
+					self.pending_splice.as_ref().and_then(|pending_splice| {


They could have sent any arbitrary my_current_funding_locked_txid, so we need to check if we are aware of it. Maybe that is redundant with checks when the implicit splice_locked is processed? At very least this is explicitly following the language in the spec. Also, my_current_funding_locked_txid could have been their channel_ready, so we wouldn't want to infer a splice_locked from that.

jkczyz · 2025-07-09T00:04:40Z

lightning/src/ln/channel.rs

+				.find(|funding| funding.get_funding_txid() == Some(funding_txid))
+				.and_then(|_| {
+					self.pending_splice.as_ref().and_then(|pending_splice| {
+						(Some(funding_txid) != pending_splice.received_funding_txid)


Whether we sent ours isn't important here. This is checking if we've seen the splice_locked that they claimed to have last sent. Either pending_splice.received_funding_txid is some other txid that they had previously sent or None if we don't think they have sent one yet.

jkczyz · 2025-07-09T00:15:21Z

lightning/src/ln/channelmanager.rs

+		if let Some(splice_locked) = implicit_splice_locked {
+			self.internal_splice_locked(counterparty_node_id, &splice_locked)?;
+		}
+
 		Ok(NotifyOption::SkipPersistHandleEvents)


Looks like we always persist when internal_splice_locked returns Ok, so doing that here, too.

jkczyz requested a review from wpaulino June 24, 2025 00:12

jkczyz mentioned this pull request Jun 24, 2025

Dual-funded channels and Splicing Project Tracking #1621

Open

7 tasks

jkczyz added this to Weekly Goals Jun 26, 2025

jkczyz assigned jkczyz and unassigned jkczyz Jun 26, 2025

jkczyz force-pushed the 2025-06-channel-reestablish branch 2 times, most recently from 06c0dfc to f000b76 Compare June 27, 2025 17:04

jkczyz marked this pull request as ready for review June 27, 2025 17:12

jkczyz self-assigned this Jul 3, 2025

jkczyz moved this to Goal: Merge in Weekly Goals Jul 3, 2025

Add features for splicing

0fd2037

While splicing is not yet fully supported, checking if the feature has been negotiated is needed for changes to the channel_reestablish logic.

jkczyz force-pushed the 2025-06-channel-reestablish branch from f000b76 to e2ea3bf Compare July 7, 2025 21:02

wpaulino reviewed Jul 7, 2025

View reviewed changes

jkczyz added 6 commits July 8, 2025 18:01

f - docs

3b30cc7

f - their_features

594eb83

Update channel_reestablish logic for channel_ready

297bfa0

When splicing is negotiated, channel_ready must be retransmitted when your_last_funding_locked is not set. Further, the current logic for retransmitting channel_ready is only applicable when splicing is not negotiated.

f - their_features

00a4ac0

jkczyz and others added 8 commits July 8, 2025 18:37

Send splice_locked on channel_reestablish

070e881

The channel_reestablish protocol supports retransmitting splice_locked messages as needed. Add support for doing such when handling channel_reestablish messages.

Send channel_ready on channel_reestablish

81e8e06

The channel_reestablish protocol supports retransmitting channel_ready messages as needed. Add support for doing such when handling channel_reestablish messages.

f - persist for implicit_splice_locked

69be701

jkczyz force-pushed the 2025-06-channel-reestablish branch from e2ea3bf to 69be701 Compare July 9, 2025 00:17

jkczyz commented Jul 9, 2025

View reviewed changes

	if matches!(self.context.channel_state, ChannelState::AwaitingChannelReady(_)) {
	// If we're waiting on a monitor update, we shouldn't re-send any channel_ready's.
	if !self.context.channel_state.is_our_channel_ready() \|\|
	self.context.channel_state.is_monitor_update_in_progress() {
	if msg.next_remote_commitment_number != 0 {
	return Err(ChannelError::close("Peer claimed they saw a revoke_and_ack but we haven't sent channel_ready yet".to_owned()));
	}
	// Short circuit the whole handler as there is nothing we can resend them
	return Ok(ReestablishResponses {
	channel_ready: None,
	raa: None, commitment_update: None,
	order: RAACommitmentOrder::CommitmentFirst,
	shutdown_msg, announcement_sigs,
	tx_signatures: None,
	tx_abort: None,
	});
	}

Update channel_reestablish for splicing #3886

Are you sure you want to change the base?

Update channel_reestablish for splicing #3886

Uh oh!

Conversation

jkczyz commented Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ldk-reviews-bot commented Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ldk-reviews-bot commented Jun 26, 2025

Uh oh!

jkczyz commented Jun 27, 2025

Uh oh!

codecov bot commented Jun 27, 2025

Codecov Report

Uh oh!

ldk-reviews-bot commented Jun 28, 2025

Uh oh!

ldk-reviews-bot commented Jun 30, 2025

Uh oh!

ldk-reviews-bot commented Jul 2, 2025

Uh oh!

ldk-reviews-bot commented Jul 5, 2025

Uh oh!

ldk-reviews-bot commented Jul 7, 2025

Uh oh!

jkczyz commented Jul 7, 2025

Uh oh!

wpaulino left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ldk-reviews-bot commented Jul 7, 2025

Uh oh!

jkczyz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Update `channel_reestablish` for splicing #3886

Update `channel_reestablish` for splicing #3886

jkczyz commented Jun 24, 2025 •

edited

Loading

ldk-reviews-bot commented Jun 24, 2025 •

edited

Loading